AES-256 ZIP 归档# PRO

Archive 类用于处理 ZIP 和 7z 归档文件。 ZIP 可以按条目修改，也可以创建和解压 AES-256 加密归档；7z 方法支持 AES-256 加密、进度和取消。

#概述

Archive 提供了灵活的接口来管理压缩包内容，包括：

• 打开已有归档或创建新归档；
• 添加文件、目录或自定义数据；
• 支持异步与同步两种操作模式；
• 提取文件内容到内存或磁盘；
• 删除归档中的条目；
• 支持自定义压缩算法（如 deflate）；
• 可通过 entries() 获取归档中的所有条目信息。
• 创建和解压使用 AES-256 加密的 ZIP 归档。
• 创建、列出和解压 AES-256 加密的 7z 归档。

#静态方法

#static openForMode(path: string, accessMode: "create" | "update" | "read", options?: { pathEncoding?: Encoding }): Archive

打开 ZIP 归档文件。返回实例上的方法仅适用于 ZIP。

参数：

返回值： 返回一个 Archive 对象。

示例：

const archive = Archive.openForMode("/tmp/example.zip", "update")

#static createZip(options: ZipCreateOptions): Promise<ZipArchiveResult>

创建 ZIP 归档。提供 password 时使用 WinZip AES-256 加密文件内容；不提供密码时创建普通 ZIP。目标文件必须不存在。

const result = await Archive.createZip({
  sourcePath: "/tmp/photos",
  destinationPath: "/tmp/photos.zip",
  password: "a-strong-password",
  shouldKeepParent: true
})

console.log(result.entryCount, result.outputBytes)

ZIP 加密不会隐藏归档内的文件名。如需同时隐藏文件名和归档信息，请使用 create7z() 并保持 encryptHeader: true。

#static extractZip(options: ZipExtractOptions): Promise<ZipArchiveResult>

把普通或密码保护的 ZIP 解压到新目录。目标目录已存在、密码错误或归档超过限制时会失败，不会留下不完整的目标目录。

try {
  const result = await Archive.extractZip({
    sourcePath: "/tmp/photos.zip",
    destinationPath: "/tmp/restored-photos",
    password: "a-strong-password"
  })
  console.log(`已解压 ${result.entryCount} 个条目`)
} catch (error) {
  if (error.name === "ArchiveError") {
    console.log(error.code, error.message)
  }
}

#static create7z(options: SevenZipCreateOptions): SevenZipTask

创建 AES-256 加密的 7z 归档。目标文件必须不存在；文件内容始终加密，文件名和归档元数据默认也会加密。

const task = Archive.create7z({
  sources: [
    "/tmp/report.pdf",
    { path: "/tmp/photos", archivePath: "attachments/photos" }
  ],
  destinationPath: "/tmp/backup.7z",
  password: "a-strong-password"
})

task.onProgress = progress => {
  console.log(`${Math.round(progress.fractionCompleted * 100)}% ${progress.path}`)
}

const result = await task.result
console.log(result.destinationPath, result.outputBytes)

暂不支持空源目录和符号链接。

#static list7z(options: SevenZipListOptions): Promise<ArchiveEntry[]>

列出 7z 归档中的条目。归档 header 已加密时必须提供密码。

const entries = await Archive.list7z({
  sourcePath: "/tmp/backup.7z",
  password: "a-strong-password"
})

for (const entry of entries) {
  console.log(entry.path, entry.uncompressedSize, entry.isEncrypted)
}

#static extract7z(options: SevenZipExtractOptions): SevenZipTask

将 7z 归档解压到新目录。不安全的条目路径和超过限制的归档会被拒绝，且不会覆盖已有目标。

const task = Archive.extract7z({
  sourcePath: "/tmp/backup.7z",
  destinationPath: "/tmp/restored",
  password: "a-strong-password"
})

try {
  const result = await task.result
  console.log(`已解压 ${result.entryCount} 个条目`)
} catch (error) {
  if (error.name === "ArchiveError") {
    console.log(error.code, error.message)
  }
}

#SevenZipTask 类型

create7z() 和 extract7z() 返回可报告进度和取消的任务对象。

ArchiveError.code 可能为 invalidArguments、permissionDenied、sourceNotFound、destinationExists、invalidPasswordOrCorruptArchive、unsafeEntryPath、unsupportedEntryType、archiveLimitExceeded、cancelled、outOfSpace、ioError 或 internalError。

#属性

#path: string

归档文件的路径。

示例：

console.log(archive.path)

#data: Data | null

归档的二进制数据内容（如果以内存方式打开）。

#实例方法

#entries(pathEncoding?: Encoding): ArchiveEntry[]

获取归档中所有条目的信息。

参数： pathEncoding 可选，指定路径的编码方式，默认为 "utf-8"。

返回值： 返回一个 ArchiveEntry 对象的数组，包含所有条目的信息。

#getEntryPaths(encoding?: Encoding): string[]

获取归档中所有条目的路径。

参数： encoding 可选，指定路径的编码方式，默认为 "utf-8"。

返回值： 返回一个字符串数组，包含所有条目的路径。

#getEntry(path: string): ArchiveEntry | null

获取归档中指定路径的条目。

参数： path 要获取的条目的路径。

返回值： 返回一个 ArchiveEntry 对象，或 null 如果条目不存在。

#contains(path: string): boolean

判断归档中是否包含指定路径的条目。

参数：

path 要判断的条目的路径。

返回值： true 表示存在，false 表示不存在。

示例：

if (archive.contains("README.md")) {
  console.log("Archive contains README.md")
}

#addEntry(path: string, toPath: string, options?: { compressionMethod?: "deflate" | "none"; bufferSize?: number }): Promise<void>

向归档中添加一个现有文件（异步）。

参数：

示例：

await archive.addEntry("/tmp/input.txt", "docs/input.txt", {
  compressionMethod: "deflate"
})

#addEntrySync(path: string, toPath: string, options?)

同步版本，与 addEntry() 功能相同。 若添加失败会抛出异常。

#addFileEntry(path: string, uncompressedSize: number, provider: (offset: number, length: number) => Data, options?): Promise<void>

通过数据提供函数添加文件到归档（异步）。

参数：

示例：

const data = Data.fromRawString("abcdefg".repeat(100))
await archive.addFileEntry("fromMemory.txt", data.count, (offset, length) => {
  return data.slice(offset, offset + length)
})

#addFileEntrySync(...)

同步版本，与上方异步方法功能一致。

#addDirectoryEntry(path: string, options?): Promise<void>

向归档中添加一个目录。

参数：

示例：

await archive.addDirectoryEntry("images/")

#addDirectoryEntrySync(...)

同步版本，与 addDirectoryEntry() 功能相同。

#removeEntry(path: string, options?): Promise<void>

从归档中删除指定路径的条目（异步）。

参数：

示例：

await archive.removeEntry("old/file.txt")

#removeEntrySync(...)

同步版本，与 removeEntry() 功能相同。

#extract(path: string, consumer: (data: Data) => void, options?): Promise<void>

从归档中提取指定文件，并将其数据通过回调函数分块返回（异步）。

参数：

示例：

await archive.extract("docs/manual.txt", (chunk) => {
  console.log("Received chunk:", chunk.count)
})

#extractSync(...)

同步版本，与 extract() 功能一致。

#extractTo(path: string, to: string, options?): Promise<void>

将归档中的文件或目录提取到指定磁盘路径（异步）。

参数：

示例：

await archive.extractTo("docs/", "/tmp/extracted/")

#extractToSync(...)

同步版本，与 extractTo() 功能一致。

#ArchiveEntry 类型

ArchiveEntry 表示归档中的一个条目（文件、目录或符号链接）。

示例：

for (const entry of archive.entries()) {
  console.log(`[${entry.type}] ${entry.path} (${entry.uncompressedSize} bytes)`)
}

#综合示例

#创建新压缩包并添加文件

const archive = Archive.openForMode("/tmp/example.zip", "update")

await archive.addEntry(
  "/tmp/hello.txt",
  "docs/hello.txt",
  { compressionMethod: "deflate" }
)

await archive.addDirectoryEntry("images/")
await archive.addEntry("/tmp/logo.png", "images/logo.png")

console.log("Archive entries:", archive.entries().length)

#提取文件到本地目录

const archive = Archive.openForMode("/tmp/example.zip", "read")
await archive.extractTo("docs/hello.txt", "/tmp/unpacked/hello.txt")